完整程式碼可在 GitHub 專案中找到：Finetune-30-days-demo / day-21

在過去 20 天，我們完成了任務排程、實驗追蹤、認證與 Audit Log，平台逐漸具備「能跑起來」的能力。

但還有一個問題：模型只存在於個別使用者的資料夾裡，無法被他人共享或重用。

換句話說，我們能訓練出模型，但沒有地方「登錄」它。

今天的目標，就是讓平台具備「模型登錄 + 智能推薦」的能力，使每個模型都能成為知識庫中的一份可重用資產。

一、模型共享的設計概念

1. 建立集中式的模型登錄區（Model Registry）

我們在後端新增了 data/model_registry/ 目錄，作為所有模型的共用倉庫。
每當任務完成並訓練出模型時，系統會：

1. 將該模型的資訊（名稱、任務、語言、指標等）整理成 Model Card
2. 儲存為一份 JSON 檔案，放進共用的 Registry 目錄
3. 透過統一 API 提供搜尋與推薦功能

✅ 這樣，每個訓練完成的模型不再只屬於某個使用者，
而是自動登錄到平台的公共模型目錄，成為團隊可查詢、可重用的資產。

2. Model Card 的內容與結構

每個模型卡（model_card.json）記錄模型的所有關鍵資訊與訓練結果，例如：

{
  "id": "chinese-sentiment-v1",
  "name": "Chinese Sentiment Model",
  "base_model": "bert-base-chinese",
  "language": "zh",
  "task": "sentiment",
  "description": "Fine-tuned BERT for Chinese movie reviews",
  "metrics": { "accuracy": 0.89 },
  "tags": ["中文", "情感分析", "bert"],
  "embedding": [0.1, 0.2, -0.05, 0.3]
}

透過這些 metadata，就能快速搜尋、比對、推薦模型。

二、共享與推薦的關鍵邏輯

1. 模型搜尋（Search）

GET /models/search
根據模型的 metadata（任務、語言、base model、tags）進行過濾。

🔍 範例：

我要找「英文的 text-classification 模型」

回傳：

[
  {
    "id": "default_experiment_20250926",
    "name": "default_experiment",
    "base_model": "distilbert-base-uncased",
    "language": "en",
    "task": "text-classification",
    "metrics": { "accuracy": 0.48, "loss": 0.66 },
    "tags": ["glue", "lora"]
  }
]

2. 模型推薦（Recommend）

POST /models/recommend
透過 embedding 相似度，找出與查詢最相關的模型。

embedding 並不是模型權重，而是代表「模型描述」的語義向量。
它讓平台可以計算語意上的相似程度，實現更自然的推薦。

範例：

使用者查詢：「中文情感分析模型」
→ 平台將查詢轉換成 embedding 向量
→ 計算與所有 model_card 的 cosine similarity
→ 回傳最相似的模型（例如 0.98 分）

這一步，平台開始具備「語義搜尋 (semantic search)」能力，
不再只靠關鍵字，而能理解「意思相近」的模型。

三、共享的落地機制

模型的共享不需要手動上傳，而是 由訓練流程自動登錄：

1. 任務完成後，自動呼叫 save_model_card()
2. 儲存到 data/model_registry
3. 立即可被 /models/search 或 /models/recommend 查到

這樣一來，開發者不需要記錄模型在哪裡、叫什麼名字，
只要在前端搜尋「QA 中文分類模型」，平台就會自動推薦最接近的模型版本。

🚀 平台因此從「個人沙盒」進化成「共享知識庫」。

四、未來優化方向

目前 /models/recommend 仍需直接輸入 embedding 向量。
未來可改成自然語言輸入，例如：

{
  "query": "客服對話意圖分類模型"
}

後端自動用 sentence-transformers 轉換為向量後推薦，
讓推薦功能對非工程師使用者更直覺。

今天的進度，讓平台從「單純紀錄實驗」邁向 模型共享與重用。開發者能快速搜尋合適模型，使用者也能透過推薦減少重複訓練，團隊知識因此逐漸沉澱下來。這一步，平台不再只是「檔案收集站」，而是真正的 協作空間，開始展現「知識庫」的價值。

📎 AI 協作記錄：今日開發指令

# 1. 新增模型共享模組
請幫我建立 `src/models/model_registry.py`，功能包含：
- 定義 ModelCard 結構（dataclass 或 Pydantic）
- 提供 `save_model_card`、`search_models`、`recommend_models`
- recommend_models 內部實作 cosine similarity

# 2. 新增 API
請幫我新增 `src/api/routes/models.py`，功能包含：
- GET /models/search → 呼叫 search_models
- POST /models/recommend → 呼叫 recommend_models
- 回傳 JSON，格式包含 id/name/base_model/language/task/metrics